﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
    <title>Comdiv QWeb coding rules</title>
</head>
<body>
       <h1>Javasctipt library rules</h1>
       <h2>Common</h2>
       <ul>
        <li>
        QJS is prototype based library and follow 'prototype'-like style of coding, so 
            <ul>
                <li>
        for core  operations as object/class definition and extension we uses
         #prototype.Object and #prototype.Class facilities and other basic extensions
                    - Function.bind, Array/Hash/Enum and so on</li>
                <li>
    for Ajax we uses Ajax.Request and Ajax.Updater
                </li>
            </ul>
        </li>
        <li>
       We always uses soft definition of namespace/object ieararchy - if we want to use
    "my.best.obj" we must define it through set of window.my = window.my || {}; window.my.best = window.my.best ||{};
    and so on to avoid illegal redefining of objects due to order of script loading.
    If you are sure that script wi;ll executed with qweb/core.js loaded it can use 
        qweb.defineGlobal('my.best.obj') to do it.
        </li>

        <li>
        All JS modules MUST be safe for global naming space and not make some of garbage:<br />
        main form  is:<br />
((function(){<br />
... any code<br />
})())<br /> which is used for usual scripts which setup framework and pure JSON:<br />
{<br />
...<br />
}<br />
for scripts which provide some objects
        </li>
       </ul>
       <h2>Naming style</h2>
       <p>JS not supports visibility of members but conditionally we suppose that: </p>
       <p>Public - is client api for using from other code or directly by client.</p>
       <p>Protected - is members/classes intended to be used in deep scripting or be 
           overrided or be replaced in descending/extensions and similar scenarios</p>
       <p>Private - members that intented to be used only internaly by object that contains 
           it and have not to be overriden/replaced</p>
       <ul>
        <li>
            namespaces - public only - camelCase
        </li>
           <li>
               public classes/objects - camelCase</li>
           <li>
               protected classes/objects - _camelCase</li>
           <li>
               public constants - UPPERCASE_WITHUNDERSCORES</li>
           <li>
               protected constants - _UPPERCASE_WITHUNDERSCORES</li>
           <li>
               private constants - __UPPERCASE_WITHUNDERSCORES</li>
           <li>
               public fields - camelCase</li>
           <li>
               protected fields - _camelCase</li>
           <li>
               private fields - __camelCase</li>
           <li>
               public methods - camelCase()</li>
           <li>
               protected methods - _camelCase()</li>
           <li>
               private methods - __camelCase()</li>
           <li>
               var - camelCase</li>
           <li>
               local - lowercase</li>
       </ul>
       <h2>
           Method arguments</h2>
       <p>
           Recomend to use balanced solution for arguments with some rules:</p>
       <ol>
           <li>if method ALWAYS will have certain ZERO, ONE ot MAXIMALLY TWO parameters we use 
               usual notation function(arg1,...)</li>
           <li>if method will have 3 or more parameters with possible extending of tem we use 
               prototype - oriented ONEOBJECT notation: function(args) with first operand args 
               = Object.extend(defaultArgs, args||{})&nbsp; to prepare mostly valid argument&#39;s 
               set</li>
           <li>if we in 95% use method AS IT MENTIONED in (1) but in 5% we need some extras - 
               we uses hybrid notation function(arg1, arg2, args)<br />
               and initialization args = Object.extend( Object.extend ( defaultArgs, args || {} 
               ), { argnam1 : arg1, argname2 : arg2}) so by interface method<br />
               uses simple notation for caller as in (1), but internally it works with complex 
               object as in (2)</li>
           <li>If we have common api with big amount of paramters and usual uses are used some 
               sub sets of them we make &#39;overload&#39; - we define &#39;protected&#39; method as 
               _functionName(args) in (2) notation and&nbsp; creates it&#39;s overloads/shortcuts 
               as callVariant1(arg1...) in (1) or (3) forms</li>
       </ol>
       <h2>
           Statics and Instances</h2>
       <p>
           Follow this rules:</p>
       <ol>
           <li>If object is used in multithread scenarions (setTimeout, events, ajax requests 
               and so on.) and have a state - YOU MUST define it as Class, use<br />
               it&#39;s prototype definition and new() instantiation (INSTANCEABLE)</li>
           <li>If object have component-like behavior (get an element as parameter and setup 
               some behaviour on it) - YOU MUST MAKE IT INSTANCEABLE</li>
           <li>Most of APIs CAN BE defined as STATICS in global scope for simplifing of it&#39;s 
               usage and performance issues</li>
           <li>If you cannot decide which model preferable - choose instanceable due to it&#39;s 
               more safety</li>
       </ol>
       <h2>
           Debugging and Testing</h2>
       <p>
           Debugging is not simple in working application if JS loaded by AJAX/eval. So if 
           your want to debug some scripts your must load them<br />
           by qweb.load({name:..., type:&#39;tag&#39;}) in head of page. All following AJAX 
           requests will be processed from cache. You can make such script conditional<br />
           and check your custom options to DEBUG/USUAL mode. Conclusion - for now we have 
           not valid and standard solution to<br />
           make QJS more debuggable.</p>
       <p>
           Testing - we start to write own testcase JS library with integrated QJS support 
           but now it&#39;s in starting mode - no any suggestions for<br />
           testing method choose</p>
</body>
</html>
